Restructure VB.NET async article to follow C# breakfast tutorial format with proper VB syntax #48186

Copilot · 2025-08-29T15:49:58Z

The Visual Basic async programming documentation was using an incorrect C# article as a reference and had an academic structure that didn't match the recommended tutorial approach. This PR completely restructures the VB.NET async article to follow the correct C# article format (https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/) while using proper Visual Basic syntax throughout.

Key Changes

Complete structural overhaul:

Replaced the academic article structure with the practical breakfast-making tutorial approach
Changed from abstract concepts to concrete, progressive examples showing synchronous → simple async → concurrent async patterns
Removed the technical diagram section and replaced with hands-on code examples

VB.NET breakfast tutorial implementation:

Created comprehensive VB.NET breakfast code examples that mirror the C# tutorial structure
All code uses proper Visual Basic syntax: Task(Of T), Async Function, Await, Module, etc.
Progressive examples show the evolution from blocking synchronous code to efficient concurrent async code

Improved consistency and readability:

All explanatory text now uses VB.NET method names and syntax consistently
Replaced C#-style examples with idiomatic Visual Basic patterns
Added proper VB.NET exception handling examples
Updated all cross-references to use VB.NET conventions

Modern .NET alignment:

Updated code snippets to target .NET 8.0
Removed outdated references and aligned with current async/await best practices
Added comparison between Async/Await and ContinueWith patterns in VB.NET

Enhanced documentation format:

Converted all code snippets to the modern :::code format for better rendering
Fixed relative links to follow documentation standards
Added visual diagrams from the C# version to illustrate timing concepts
Included proper AI-generated content disclosure

The article now provides the same high-quality tutorial experience as the C# version but with proper Visual Basic syntax and conventions throughout, eliminating the confusion reported in issue #17731.

Fixes #17731.
Fixes #37289 (duplicate).

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Internal previews

📄 File	🔗 Preview link
docs/visual-basic/programming-guide/concepts/async/index.md	Asynchronous programming with Async and Await (Visual Basic)

Co-authored-by: BillWagner <[email protected]>

BillWagner · 2025-08-29T17:24:52Z

@copilot You picked the wrong C# article as a source. Use the one referenced in this comment: #17731 (comment)

The correct article is this one: https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/ You can reuse those images for the VB article as well.

Co-authored-by: BillWagner <[email protected]>

Copilot · 2025-08-29T17:36:16Z

@copilot You picked the wrong C# article as a source. Use the one referenced in this comment: #17731 (comment)

The correct article is this one: ht...

I've restructured the VB article to follow the correct C# article format using the breakfast tutorial approach. The article now uses the same progressive teaching structure (synchronous → simple async → concurrent async) but with proper VB.NET syntax throughout. All code examples have been converted to the breakfast metaphor with VB.NET conventions. Commit: 07fcef0

BillWagner

This is much closer. I have a few things to address and this will be ready.

docs/visual-basic/programming-guide/concepts/async/index.md

docs/visual-basic/programming-guide/concepts/async/snippets/breakfast/breakfast.vbproj

BillWagner · 2025-08-29T18:02:42Z

@copilot Please address the remaining comments.

…t, add C# diagrams Co-authored-by: BillWagner <[email protected]>

Copilot · 2025-08-29T18:10:16Z

@copilot Please address the remaining comments.

Addressed all remaining comments: fixed relative link, converted snippets to ::: format, copied and referenced all diagrams from the C# version, and ensured the project builds successfully. Commit: 41f0f0b

BillWagner

Once I upgrade to .NET 9, this is ready.

docs/visual-basic/programming-guide/concepts/async/snippets/breakfast/breakfast.vbproj

…eakfast/breakfast.vbproj

gewarren · 2025-09-05T16:12:44Z

docs/visual-basic/programming-guide/concepts/async/index.md


-  The suspension of an async method at an `Await` expression doesn't constitute an exit from the method, and `Finally` blocks don't run.
+Notice that quite a few tasks finish between the time when the toaster catches fire and the system observes the exception. When a task that runs asynchronously throws an exception, that task is **faulted**. The <xref:System.Threading.Tasks.Task> object holds the exception thrown in the <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property. Faulted tasks throw an exception when the `Await` expression is applied to the task.


Suggested change

Notice that quite a few tasks finish between the time when the toaster catches fire and the system observes the exception. When a task that runs asynchronously throws an exception, that task is **faulted**. The <xref:System.Threading.Tasks.Task> object holds the exception thrown in the <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property. Faulted tasks throw an exception when the `Await` expression is applied to the task.

Notice that quite a few tasks finish between the time when the toaster catches fire and the system observes the exception. When a task that runs asynchronously throws an exception, that task is **faulted**. The <xref:System.Threading.Tasks.Task> object holds the exception that was thrown in the <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property. Faulted tasks *throw* the exception when the `Await` expression is applied to the task.

gewarren · 2025-09-05T16:13:03Z

docs/visual-basic/programming-guide/concepts/async/index.md

+- How an exception is stored in a faulted task
+- How an exception is unpackaged and rethrown when code waits (`Await`) on a faulted task


Suggested change

- How an exception is stored in a faulted task

- How an exception is unpackaged and rethrown when code waits (`Await`) on a faulted task

- How an exception is stored in a faulted task.

- How an exception is unpackaged and rethrown when code waits (`Await`) on a faulted task.

gewarren · 2025-09-05T16:14:15Z

docs/visual-basic/programming-guide/concepts/async/index.md


-`Async` and `Await` are contextual keywords. For more information and examples, see the following topics:
+When code running asynchronously throws an exception, the exception is stored in the <xref:System.Threading.Tasks.Task> object. The <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property is a <xref:System.AggregateException> object because more than one exception might be thrown during asynchronous work. Any exception thrown is added to the <xref:System.AggregateException.InnerExceptions?displayProperty=nameWithType> collection. If the `Exception` property is null, a new `AggregateException` object is created and the thrown exception is the first item in the collection.


Suggested change

When code running asynchronously throws an exception, the exception is stored in the <xref:System.Threading.Tasks.Task> object. The <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property is a <xref:System.AggregateException> object because more than one exception might be thrown during asynchronous work. Any exception thrown is added to the <xref:System.AggregateException.InnerExceptions?displayProperty=nameWithType> collection. If the `Exception` property is null, a new `AggregateException` object is created and the thrown exception is the first item in the collection.

When code running asynchronously throws an exception, the exception is stored in the <xref:System.Threading.Tasks.Task> object. The <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property is an <xref:System.AggregateException> object because more than one exception might be thrown during asynchronous work. Any exception thrown is added to the <xref:System.AggregateException.InnerExceptions?displayProperty=nameWithType> collection. If the `Exception` property is null, a new `AggregateException` object is created and the thrown exception is the first item in the collection.

gewarren · 2025-09-05T16:16:04Z

docs/visual-basic/programming-guide/concepts/async/index.md


-## <a name="BKMK_ReturnTypesandParameters"></a> Return types and parameters
+> [!TIP]
+> The recommended practice is for any argument validation exceptions to emerge *synchronously* from task-returning methods. For more information and examples, see [Exceptions in task-returning methods](/dotnet/fundamentals/exceptions/creating-and-throwing-exceptions#exceptions-in-task-returning-methods).


Suggested change

> The recommended practice is for any argument validation exceptions to emerge *synchronously* from task-returning methods. For more information and examples, see [Exceptions in task-returning methods](/dotnet/fundamentals/exceptions/creating-and-throwing-exceptions#exceptions-in-task-returning-methods).

> The recommended practice is for any argument validation exceptions to emerge *synchronously* from task-returning methods. For more information and examples, see [Exceptions in task-returning methods](../../../../fundamentals/exceptions/creating-and-throwing-exceptions.md#exceptions-in-task-returning-methods).

gewarren · 2025-09-05T16:16:31Z

docs/visual-basic/programming-guide/concepts/async/index.md

+Console.WriteLine("Fire! Toast is ruined!")
+Throw New InvalidOperationException("The toaster is on fire")


Suggested change

Console.WriteLine("Fire! Toast is ruined!")

Throw New InvalidOperationException("The toaster is on fire")

' Console.WriteLine("Fire! Toast is ruined!")

' Throw New InvalidOperationException("The toaster is on fire")

Initial plan

c9d05e5

Copilot AI assigned Copilot and BillWagner Aug 29, 2025

Copilot started work on behalf of BillWagner August 29, 2025 15:50 View session

dotnet-policy-service bot added the okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings. label Aug 29, 2025

Update VB async article structure and add VB code snippets

530e4e4

Co-authored-by: BillWagner <[email protected]>

dotnet-policy-service bot added the dotnet-visualbasic/svc label Aug 29, 2025

Copilot AI changed the title ~~[WIP] Code diagram shows C# but this is a VB.NET specific page~~ Fix VB.NET async documentation to use VB-specific code examples and method names Aug 29, 2025

Copilot finished work on behalf of BillWagner August 29, 2025 16:01

Copilot AI requested a review from BillWagner August 29, 2025 16:01

Copilot started work on behalf of BillWagner August 29, 2025 17:25 View session

Restructure VB async article to follow C# breakfast tutorial format

07fcef0

Co-authored-by: BillWagner <[email protected]>

Copilot AI changed the title ~~Fix VB.NET async documentation to use VB-specific code examples and method names~~ Restructure VB.NET async article to follow C# breakfast tutorial format with proper VB syntax Aug 29, 2025

Copilot finished work on behalf of BillWagner August 29, 2025 17:37

BillWagner reviewed Aug 29, 2025

View reviewed changes

BillWagner added 2 commits August 29, 2025 14:02

Update docs/visual-basic/programming-guide/concepts/async/index.md

add9c9f

Update docs/visual-basic/programming-guide/concepts/async/index.md

045276a

Copilot started work on behalf of BillWagner August 29, 2025 18:02 View session

Address review feedback: fix relative link, convert to ::: code forma…

41f0f0b

…t, add C# diagrams Co-authored-by: BillWagner <[email protected]>

Copilot finished work on behalf of BillWagner August 29, 2025 18:11

Copilot AI requested a review from BillWagner August 29, 2025 18:11

BillWagner approved these changes Aug 29, 2025

View reviewed changes

docs/visual-basic/programming-guide/concepts/async/snippets/breakfast/breakfast.vbproj Outdated Show resolved Hide resolved

Update docs/visual-basic/programming-guide/concepts/async/snippets/br…

031dcec

…eakfast/breakfast.vbproj

BillWagner marked this pull request as ready for review August 29, 2025 18:29

BillWagner requested a review from a team as a code owner August 29, 2025 18:29

BillWagner requested a review from adegeo August 29, 2025 18:30

BillWagner requested a review from gewarren September 2, 2025 21:22

gewarren approved these changes Sep 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Restructure VB.NET async article to follow C# breakfast tutorial format with proper VB syntax #48186

Restructure VB.NET async article to follow C# breakfast tutorial format with proper VB syntax #48186

Uh oh!

Copilot AI commented Aug 29, 2025 •

edited by github-actions bot

Loading

Uh oh!

BillWagner commented Aug 29, 2025

Uh oh!

Copilot AI commented Aug 29, 2025

Uh oh!

BillWagner left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BillWagner commented Aug 29, 2025

Uh oh!

Copilot AI commented Aug 29, 2025

Uh oh!

BillWagner left a comment

Uh oh!

Uh oh!

gewarren Sep 5, 2025

Uh oh!

gewarren Sep 5, 2025

Uh oh!

gewarren Sep 5, 2025

Uh oh!

gewarren Sep 5, 2025

Uh oh!

gewarren Sep 5, 2025

Uh oh!

Uh oh!


		The suspension of an async method at an `Await` expression doesn't constitute an exit from the method, and `Finally` blocks don't run.
		Notice that quite a few tasks finish between the time when the toaster catches fire and the system observes the exception. When a task that runs asynchronously throws an exception, that task is faulted. The <xref:System.Threading.Tasks.Task> object holds the exception thrown in the <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property. Faulted tasks throw an exception when the `Await` expression is applied to the task.

		- How an exception is stored in a faulted task
		- How an exception is unpackaged and rethrown when code waits (`Await`) on a faulted task


		`Async` and `Await` are contextual keywords. For more information and examples, see the following topics:
		When code running asynchronously throws an exception, the exception is stored in the <xref:System.Threading.Tasks.Task> object. The <xref:System.Threading.Tasks.Task.Exception?displayProperty=nameWithType> property is a <xref:System.AggregateException> object because more than one exception might be thrown during asynchronous work. Any exception thrown is added to the <xref:System.AggregateException.InnerExceptions?displayProperty=nameWithType> collection. If the `Exception` property is null, a new `AggregateException` object is created and the thrown exception is the first item in the collection.

	> The recommended practice is for any argument validation exceptions to emerge synchronously from task-returning methods. For more information and examples, see [Exceptions in task-returning methods](/dotnet/fundamentals/exceptions/creating-and-throwing-exceptions#exceptions-in-task-returning-methods).
	> The recommended practice is for any argument validation exceptions to emerge synchronously from task-returning methods. For more information and examples, see [Exceptions in task-returning methods](../../../../fundamentals/exceptions/creating-and-throwing-exceptions.md#exceptions-in-task-returning-methods).

		Console.WriteLine("Fire! Toast is ruined!")
		Throw New InvalidOperationException("The toaster is on fire")

Restructure VB.NET async article to follow C# breakfast tutorial format with proper VB syntax #48186

Are you sure you want to change the base?

Restructure VB.NET async article to follow C# breakfast tutorial format with proper VB syntax #48186

Uh oh!

Conversation

Copilot AI commented Aug 29, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Internal previews

Uh oh!

BillWagner commented Aug 29, 2025

Uh oh!

Copilot AI commented Aug 29, 2025

Uh oh!

BillWagner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BillWagner commented Aug 29, 2025

Uh oh!

Copilot AI commented Aug 29, 2025

Uh oh!

BillWagner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gewarren Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented Aug 29, 2025 •

edited by github-actions bot

Loading